Constructing Apps
Volume Number: 1
Issue Number: 3
Column Tag: C Workshop
Basics in Constructing Applications
By Robert B. Denny
Last month’s C Workshop presented an application “template”, a program shell
which can be used as the basis of many kinds of applications. The template can be used
with most C systems since there are no calls to library functions. The only external
services used are native Mac toolbox traps.
This month, we’ll look at some of the basics in constructing applications,
including the tricky area of servicing desk accessories properly. If you have access to
last month’s C Workshop, you can refer to the template application’s code for
examples. It’s not necessary, though.
Common Requirements
Most applications share several common requirements. These are:
• Overall control is via the menu bar and pull-down menus.
• Detail control and input uses both the mouse and the keyboard.
• Multiple instances of multiple types of windows serve as user interfaces.
• All desk accessories must be usable during execution of the application, within
the limits of available memory.
These requirements, combined with the Macintosh operating system, imply the
overall application setup and control structure described below.
Applications should begin by initializing all of the system services that it intends
to use. At a minimum, all applications should call InitGraf(),
InitWindows(),InitFonts(), InitMenus(), InitDialogs() and TEInit(). Some desk
accessories use dialogs, which in turn use TextEdit.
Menu Setup
Any application that supports desk accessories must support a menu bar with at
least the “Apple”, “File” and “Edit” menus. These menus must be present as required
by the Macintosh User Interface Guidelines, and desk accessories assume that they are
present. Moreover, the “File” and “Edit” menu options must also conform to the User
Interface Guidelines. Desk accessories make assumptions as to the order and meaning
of options in these menus.
The “Apple” menu must be set up to contain the desk accessories for selection and
opening. Your application must do this explicitly by first creating the menu then
adding the desk accessories via the AddResMenu() service. For example:
MenuHandle mh;
...
InsertMenu(mh = GetMenu(1), 0);
AddResMenu(mh, ‘DRVR’);
...
DrawMenuBar();
In the example, GetMenu() loads the menu resource whose ID = 1 and returns a
handle to it, which gets stored in mh. InsertMenu() then adds the menu to the menu
bar. Next, AddResMenu() appends the names of all resources of type ‘DRVR’ to the
menu. Desk accessories are “drivers” to the current Mac operating system, hence
have the resource type of ‘DRVR’. Real drivers have names beginning with ‘.’ or ‘%’
and will not get added to the menu.
The “File” menu is not used (yet) by any of the standard desk accessories. It is
up for grabs, though, and should follow the User Interface Guidelines. That is, the
items should follow the order:
Open...
Close
Save
Save as...
------
Page Setup
Print...
------
Desk accessories are free to assume that the ordering (and therefore numbering)
of menu items in the “File” menu conforms to the above.
The “Edit” menu is used by the Note Pad and other desk accessories. Again, the
layout of the menu must follow the user interface guidelines, namely:
------
Cut
------
Show Clipboard
To reiterate, the leftmost three menus must conform to the Macintosh User
Interface Guidelines stated in Inside Macintosh if the application is to support desk
accessories.
The Event Loop
The single most important character- istic of a Macintosh application is that it is
event-driven. Most Mac applications have an “event loop” as their outermost control
structure. Following initializa- tion, the application does something like:
while(TRUE)
if(!GetNextEvent(-1, & event))
continue;
switch( event.what)
... cases for each event type
... our application handles
default: /* Junk other events */
}
}
It is vitally important to understand the event loop. Most trips around the loop
circle back at the continue statement that gets executed if GetNextEvent() returns
FALSE, meaning that there is no event for us to handle. In future versions of the
Macintosh operating system which support multitasking, GetNextEvent() will
probably return control to the scheduler, giving other tasks CPU time until an event
occurs for the caller.
In any case, when an event for us does occur, GetNextEvent() returns TRUE and
fills in our event record with information describing the nature of the event. In C, the
event record can be defined as follows:
struct EventRecord
{
short what;
long message;
long when;
Point where;
short modifiers;
};
where the type Point is some mapping of the QuickDraw “point”, an ordered pair of
16-bit coordinates.
Control passes to the switch() statement, which dispatches to the event handling
function appropriate for the event type. For example, an event type of mouseDown
would dispatch to the function that handles mouse clicks.
In the example shown, the value for the first parameter to GetNextEvent() is -1.
This parameter is the event mask, and in this case, it is set to “get” all types of
events. The switch() statement should have case sections for each event type that the
application explicitly handles. Other types of events use the default case, which does
nothing.
If the event mask parameter specifies a subset of event types, those not specified
will remain on the event queue for possible later processing. This may be needed for
applications which use a certain event type to trigger processing of earlier events of
other types not normally processed. This is tricky, though, and can be the source of
some obscure bugs. Also, unprocessed events on the queue take up valuable memory
space.
If that isn’t enough, there’s a system- wide event mask that controls what event
types are recognized and queued. Your application can disable the queueing of certain
event types by calling the SetEventMask() service. If your applica- tion doesn’t
process certain event types, you should disable them in the system event mask. This
pr events wasting valuable event queue memory space with unprocessed event records.
The bottom line is ... call GetNextEvent() with an event mask of everyEvent (-1)
to dequeue all event types, then let the default case dispose of the events you aren’t
interested in.
Just prior to calling GetNextEvent(), notice the call to SystemTask(). This Mac
system service causes control to pass to each open desk accessory, in turn, then back to
the caller. Normally, one call at the beginning of the event loop is sufficient to give
desk accessories the time they need. If you have any places in your application where
you “spin your wheels”, consider calling SystemTask() to help waste some time.
In a multi-tasking version of the Mac, SystemTask() will probably do nothing.
Rather, control will be given to the task only when there is a live event for that task.
Timer services will be provided for passing control back to the scheduler (and other
tasks) when a synchronous delay is needed in the current task.
The event loop is the fundamental control structure of a Macintosh applica- tion.
If you haven’t studied The Event Manager: A Programmer’s Guide, a chapter in Inside
Macintosh, you should take the time now to do so.
Mouse-Down Events
Any application which supports desk accessories must handle mouse-down
events. A mouse click in a desk accessory window gets passed as an event to the
application. This quirk in the Mac system architecture requires the application to
determine whether the click was in a desk accessory window or in one of its own
windows. I should mention that this approach to click handling minimizes the
uncontrollable overhead in the operating system for applications which need every
available CPU cycle and which do not support desk accessories (whew!).
So, if you want to support desk accessories, your application must detect and
process mouse-down events. If you detect a mouse click, first call the Window
Manager function FindWindow() to find out where the cursor was when the mouse
button was clicked.
If FindWindow() returns the predefined constant inSysWindow, it means that the
cursor was in a desk accessory window when the mouse was clicked. If this is the case,
call the Desk Manager function SystemClick(). This passes control back to the
operating system service which handles desk accessory windows.
Other returns from FindWindow() indicate mouse clicks in windows (including
what “part” of the window) or the menu bar, or out in “no man’s land”, the desktop
background. We’ll discuss window handling in a future C Workshop. If the click is in
the menu bar, then our application must dispatch to a menu handler, another necessity
if we are to handle desk accessories.
Menu Selections
If the mouse click is “in the Menu Bar”, then our application must first
determine the selected menu number and the item number in that menu, then dispatch
accordingly. First, call the MenuSelect() service to get a longword containing both the
menu number and the item number in that menu, then use HiWord() and LoWord() to
split them up:
unsigned short menu_id, item_no;
unsigned long result;
unsigned short HiWord(), LoWord();
unsigned long MenuSelect();
...
result = MenuSelect(& event.where);
menu_id = HiWord(result);
item_no = LoWord(result);
Then use nested switch() statements to dispatch based on the menu and item
selected.
If the “Apple” menu has the desk accessories, your application must activate a
selected accessory. If the menu selected is the “Apple” menu, and you have determined
that the selection was indeed an accessory, then you simply call OpenDeskAcc() with
the name of the menu item (the desk accessory name). The latter can be obtained by
calling GetItem() with the menu item number.
The “Edit” menu must also be handled specially if desk accessories such as the
Note Pad are to be supported properly. Before trying to dispatch to your own
edit-handling functions, you must call the SystemEdit() service. If it returns FALSE,
then dispatch to your own function. If it returns TRUE, however, then the menu
selection was made while an editing desk accessory was open. The desk accessory
handled (used) the request; you must ignore it.
If you haven’t yet studied the The Desk Manager: A Programmer’s Guide, a section
of Inside Macintosh, then you should do so now. It’s required reading for programmers
who are developing applications which must support desk accessories.
Final Words: Resources Versus Static Data
I’d like to finish up this month’s C Workshop with some thoughts on the use of
resources in C programs. Pascal has no facilities for statically initializing data
structures. Therefore, Pascal program- mers have no choice but to load static data via
the resource mechanism if they are to avoid ugly space-consuming “initialization
segments”. You should carefully consider the tradeoffs before deciding whether to
make a particular data structure static in your program or to place it in a resource.
Any data that is designed to be tailored after building the application belongs in a
resource. Same with large data struc- tures that are used infrequently and can be
“purged” from the heap. They too should go in a resource.
It’s my feeling that anything else belongs in your application’s static data area if
you can affored the room. Why? The use of resources can slow down your application
markedly. On 128K systems, heap space is fragmented by frequent resource manager
activity, causing garbage collection cycles and purges to disk. Reading in of resources
to initialize static data is far slower than having them present in your application’s
address space when it is loaded. Last but not least, it is difficult to maintain programs
which contain constants that depend on the contents of resources. For example, the
numbering of menu items must track across the C code and the RMaker source as well.
As a C programmer, you have a choice.
Author’s Note
During the last couple of months, this author has received some comments
regarding bias toward a particular C language system. I feel that a few explanatory
words are in order.
It is not the present editorial policy of MacTech to review software products, or
otherwise make comparisons or recommendations. There are many Mac publications
providing this service. This publication is devoted to providing meaningful technical
information for serious programmers. Each developer must decide for himself the
system that best meets his requirements.
My philosophy of teaching strongly emphasizes both reading and writing.
Programs provided in this column are intended to serve as “reading material”. In the
interest of completeness, I feel that the particular C system used to implement a
program should be part of the program’s documentation.
I do not endorse any C language system. There are many C systems on the market
at this time, and more are appearing every month. Each of these systems has it’s own
library and interface to the native Macintosh environment.
In order to minimize the dependence on a particular C system, the example
programs given in this column will use a minimum of library support. The template
program shown in the October 1984 edition has no library dependency at all.